Model Configuration Variables

This document describes the optional environment variables available for fine-grained control over AI model availability and tool capabilities in HAWKI. These variables provide administrators with the flexibility to customize model behavior without modifying the core configuration files.

Table of Contents

1. Overview
2. Configuration Architecture
3. Variable Naming Convention
4. Model Activation Variables
5. Tool Configuration Variables
6. Provider-Specific Configuration
7. Best Practices
8. Examples

Overview

HAWKI's model configuration system allows administrators to control AI model availability and capabilities through environment variables. While the default configuration is defined in config/model_providers.php and config/model_lists/*.php, these optional environment variables provide a clean way to override settings without modifying the source code.

Why Use Environment Variables?

• Clean Configuration: Keep your .env file minimal by only including the variables you need to override
• Source Control: Avoid committing site-specific configuration changes to version control
• Flexibility: Easily enable/disable models or tools per deployment environment
• Maintainability: Configuration changes survive HAWKI updates without merge conflicts

Default Behavior

By default, these variables are not included in the .env file to keep the configuration clean and readable. The default values defined in the model list files will be used unless explicitly overridden.

Configuration Architecture

The model configuration system consists of two layers:

Layer 1: Provider Configuration

Located in config/model_providers.php, this file defines:

• Provider API endpoints and keys
• Which model list file to load for each provider
• Provider-level settings (active status, URLs)

Layer 2: Model Lists

Located in config/model_lists/, these files define:

• Individual model definitions and capabilities
• Tool availability per model
• Default activation status

The optional environment variables override the settings in Layer 2 (model lists).

Variable Naming Convention

All model and tool configuration variables follow a consistent naming pattern:

Model Activation Variables

MODELS_{PROVIDER}_{MODEL_ID}_ACTIVE

Components:

• MODELS_ - Fixed prefix for all model configuration variables
• {PROVIDER} - Provider name in uppercase (OPENAI, GWDG, GOOGLE, etc.)
• {MODEL_ID} - Model identifier with special characters converted to underscores and uppercase
• _ACTIVE - Suffix indicating model activation control

Model ID Transformation Rules:

1. Convert to uppercase
2. Replace hyphens (-) with underscores (_)
3. Replace dots (.) with underscores (_)
4. Remove any other special characters

Examples:

Original Model ID	Environment Variable
gpt-5	MODELS_OPENAI_GPT5_ACTIVE
gpt-4.1-nano	MODELS_OPENAI_GPT4_1_NANO_ACTIVE
gemini-2.0-flash	MODELS_GOOGLE_GEMINI_2_0_FLASH_ACTIVE
meta-llama-3.1-8b-instruct	MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_ACTIVE
qwen2.5-vl-72b-instruct	MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_ACTIVE

Tool Configuration Variables

MODELS_{PROVIDER}_{MODEL_ID}_TOOLS_{TOOL_NAME}

Components:

• MODELS_{PROVIDER}_{MODEL_ID} - Same as model activation prefix
• _TOOLS_ - Fixed separator indicating tool configuration
• {TOOL_NAME} - Tool name in uppercase

Available Tools:

• FILE_UPLOAD - Document and file processing capability
• VISION - Image analysis and understanding capability
• WEB_SEARCH - Real-time web search integration

Examples:

Model ID	Tool	Environment Variable
gpt-5	vision	MODELS_OPENAI_GPT5_TOOLS_VISION
gpt-5	file_upload	MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD
gemini-2.0-flash	web_search	MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH
qwen2.5-vl-72b-instruct	vision	MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION

Model Activation Variables

These variables control whether a model appears in the model selection interface and is available for use.

Variable Format

MODELS_{PROVIDER}_{MODEL_ID}_ACTIVE=true|false

Configuration Location

Model activation defaults are defined in each provider's model list file:

• OpenAI models: config/model_lists/openai_models.php
• GWDG models: config/model_lists/gwdg_models.php
• Google models: config/model_lists/google_models.php
• Ollama models: config/model_lists/ollama_models.php
• OpenWebUI models: config/model_lists/openwebui_models.php

Common Use Cases

Disable expensive models in development:

MODELS_OPENAI_GPT5_ACTIVE=false
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=false

Enable a specific models for testing:

MODELS_OPENAI_GPT4_1_NANO_ACTIVE=true
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_ACTIVE=true

Tool Configuration Variables

These variables control which capabilities are available for each model. Tools extend model functionality with features like file processing, image analysis, and web search.

Variable Format

MODELS_{PROVIDER}_{MODEL_ID}_TOOLS_{TOOL_NAME}=true|false

Available Tools

FILE_UPLOAD Tool

Purpose: Generally enables the file upload feature for a specific model. If this feature is enabled the model will by default accept PDF and Docx as well as image files in .jpeg, .jpg, and .png formats. To separately enable or disable image upload feature for vision models you should also set the vision tool (see below).

Supported Document Types: PDF, DOCX

Example Variables:

MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD=false
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_TOOLS_FILE_UPLOAD=true
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_FILE_UPLOAD=false

Use Cases:

• Disable file processing for models with limited context windows
• Enable for models optimized for document analysis
• Control costs by limiting file processing to specific models

VISION Tool

Purpose: Enables image analysis and understanding capabilities.

Supported Input: Images uploaded by users (PNG, JPG, JPEG)

Example Variables:

MODELS_OPENAI_GPT5_TOOLS_VISION=true
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true
MODELS_GOOGLE_GEMINI_2_0_FLASH_LITE_TOOLS_VISION=false

Use Cases:

• Enable for multimodal models that support vision
• Control which models handle sensitive image data

WEB_SEARCH Tool

Purpose: Enables real-time web search integration for up-to-date information.

Functionality: Allows the model to search and retrieve current information from the web

Example Variables:

MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH=true
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=true

Use Cases:

• Enable for models that benefit from current information
• Disable in restricted environments or for privacy compliance
• Control costs by limiting web search to specific use cases

Note: Currently, web search capability is primarily available for Google Gemini models.

Configuration Location

Tool defaults are defined in the model list files alongside model definitions:

// Example from config/model_lists/openai_models.php
'tools' => [
    'stream' => true,
    'file_upload' => env('MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD', false),
    'vision'=> env('MODELS_OPENAI_GPT5_TOOLS_VISION', true),
],

Tool Availability by Model Capability

Not all tools are available for all models. Tool availability depends on the model's input/output capabilities:

File Upload Tool:

• Available for most models with text processing capabilities
• Requires functional file converter (HAWKI converter or GWDG Docling)

Vision Tool Requirements:

• Model must support image input (check "input" array in model definition)

Web Search Tool:

• Currently limited to specific providers (primarily Google Gemini)
• Check model list files for web_search tool availability

By default, external API endpoints (e.g. OpenAI) are disabled for file uploads. This default setting ensures data security, privacy, and institutional sovereignty — uploaded content must not leave academic infrastructure or be reused for model training. If required, administrators can explicitly enable external providers at their own risk.

Best Practices

1. Start with Defaults

Only add environment variables when you need to override default behavior. The default configuration in model list files is designed to work well for most deployments.

2. Document Your Overrides

If you do override settings, document why in comments in your .env file:

# Disable GPT-5 to control API costs during development
MODELS_OPENAI_GPT5_ACTIVE=false

# Enable vision for Qwen VL as default vision model
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct

3. Environment-Specific Configuration

Use different .env configurations for development, staging, and production:

Development:

# Use cheaper models for development
MODELS_OPENAI_GPT4_1_NANO_ACTIVE=true
MODELS_OPENAI_GPT5_ACTIVE=false
DEFAULT_MODEL=gpt-4.1-nano

Production:

# Enable all models for production users
MODELS_OPENAI_GPT5_ACTIVE=true
MODELS_OPENAI_GPT4_1_ACTIVE=true
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=true

4. Tool Configuration Strategy

Consider your use cases when enabling tools:

Cost-Conscious Configuration:

# Minimize file processing costs
MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD=false
MODELS_OPENAI_GPT4_1_TOOLS_FILE_UPLOAD=false
# Only enable for efficient models
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_TOOLS_FILE_UPLOAD=true

Privacy-Focused Configuration:

# Disable web search to prevent external data sharing
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH=false
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=false

# Limit vision to self-hosted models
MODELS_OPENAI_GPT5_TOOLS_VISION=false
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true

Feature-Rich Configuration:

# Enable all available features
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH=true
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_VISION=true
MODELS_OPENAI_GPT5_TOOLS_VISION=true
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true

5. Model Availability Testing

After configuration changes, test model availability:

# Restart application
php artisan config:clear
php artisan config:cache

# Test model access through the web interface
# Or use HAWKI API/CLI to verify model list

6. Model List Customization

For advanced customization beyond environment variables, you can:

1. Copy and modify model list files (preserve original naming)
2. Point to custom model lists using provider environment variables:

   OPENAI_MODEL_LIST_DIR=/model_lists/custom_openai_models.php
   GWDG_MODEL_LIST_DIR=/model_lists/custom_gwdg_models.php
3. Add new models by following the model definition structure

7. Security Considerations

Disable Models with Sensitive Data:

# Disable external models for sensitive environments
MODELS_OPENAI_GPT5_ACTIVE=false
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=false

# Use only self-hosted models
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_ACTIVE=true
OLLAMA_ACTIVE=true

Control External Features:

# Disable web search to prevent data leakage
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH=false

# Disable file upload for external models
MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD=false
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_FILE_UPLOAD=false

Examples

Example 1: Cost-Optimized Development Setup

Minimize API costs during development by using cheaper models:

# .env configuration for development

# Use nano models as defaults
DEFAULT_MODEL=gpt-4.1-nano
DEFAULT_WEBSEARCH_MODEL=gemini-2.0-flash
DEFAULT_FILEUPLOAD_MODEL=meta-llama-3.1-8b-instruct
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct

# Disable expensive models
MODELS_OPENAI_GPT5_ACTIVE=false
MODELS_OPENAI_GPT4_1_ACTIVE=false
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=false

# Disable file upload for external models
MODELS_OPENAI_GPT4_1_NANO_TOOLS_FILE_UPLOAD=false
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_FILE_UPLOAD=false

# Use GWDG for file processing (if available)
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_TOOLS_FILE_UPLOAD=true

Example 2: Privacy-First Configuration

Maximize privacy by using only self-hosted or academic models:

# .env configuration for privacy-focused deployment

# Disable all commercial cloud providers
OPENAI_ACTIVE=false
GOOGLE_ACTIVE=false

# Enable GWDG academic cloud
GWDG_ACTIVE=true
GWDG_API_KEY=your-academic-api-key

# Enable self-hosted Ollama
OLLAMA_ACTIVE=true
OLLAMA_API_URL=http://localhost:11434/api/chat

# Use GWDG models as defaults
DEFAULT_MODEL=meta-llama-3.1-8b-instruct
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct
DEFAULT_FILEUPLOAD_MODEL=meta-llama-3.1-8b-instruct

# Disable web search completely
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH=false
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=false

Example 3: Feature-Rich Production Setup

Enable all features for production users:

# .env configuration for production

# Enable all providers
OPENAI_ACTIVE=true
GWDG_ACTIVE=true
GOOGLE_ACTIVE=true

# Enable premium models
MODELS_OPENAI_GPT5_ACTIVE=true
MODELS_OPENAI_GPT4_1_ACTIVE=true
MODELS_GOOGLE_GEMINI_2_5_PRO_ACTIVE=true

# Enable all tools for flagship models
MODELS_OPENAI_GPT5_TOOLS_FILE_UPLOAD=true
MODELS_OPENAI_GPT5_TOOLS_VISION=true
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_FILE_UPLOAD=true
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_VISION=true
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=true

# Enable vision for multiple models
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true
MODELS_GWDG_INTERNVL2_5_8B_TOOLS_VISION=true
MODELS_GWDG_GEMMA_3_27B_IT_TOOLS_VISION=true

Example 4: Specialized Use Case - Research & Analysis

Optimize for document analysis and reasoning:

# .env configuration for research workloads

# Enable reasoning models
MODELS_GWDG_DEEPSEEK_R1_ACTIVE=true
MODELS_GWDG_QWQ_32B_ACTIVE=true
MODELS_GWDG_QWEN3_235B_A22B_ACTIVE=true

# Enable file processing for all relevant models
MODELS_GWDG_DEEPSEEK_R1_TOOLS_FILE_UPLOAD=true
MODELS_GWDG_LLAMA_3_3_70B_INSTRUCT_TOOLS_FILE_UPLOAD=true
MODELS_GWDG_MISTRAL_LARGE_INSTRUCT_TOOLS_FILE_UPLOAD=true
MODELS_OPENAI_GPT4_1_TOOLS_FILE_UPLOAD=true

# Enable web search for research
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=true
MODELS_GOOGLE_GEMINI_2_0_FLASH_TOOLS_WEB_SEARCH=true

# Use capable models as defaults
DEFAULT_MODEL=deepseek-r1
DEFAULT_FILEUPLOAD_MODEL=mistral-large-instruct
DEFAULT_WEBSEARCH_MODEL=gemini-2.5-pro

Example 5: Testing Individual Models

Test specific model configurations:

# .env configuration for testing

# Disable all models initially
MODELS_OPENAI_GPT5_ACTIVE=false
MODELS_OPENAI_GPT4_1_ACTIVE=false
MODELS_OPENAI_GPT4_1_NANO_ACTIVE=false
MODELS_OPENAI_O4_MINI_ACTIVE=false

# Enable only the model being tested
MODELS_OPENAI_GPT4_1_NANO_ACTIVE=true
MODELS_OPENAI_GPT4_1_NANO_TOOLS_FILE_UPLOAD=true
MODELS_OPENAI_GPT4_1_NANO_TOOLS_VISION=true

# Set as default for testing
DEFAULT_MODEL=gpt-4.1-nano
DEFAULT_VISION_MODEL=gpt-4.1-nano
DEFAULT_FILEUPLOAD_MODEL=gpt-4.1-nano

Example 6: Multi-Model Strategy

Use different models for different tasks:

# .env configuration for task-specific optimization

# Fast model for general chat
DEFAULT_MODEL=gpt-4.1-nano

# Powerful model for web search
DEFAULT_WEBSEARCH_MODEL=gemini-2.5-pro
MODELS_GOOGLE_GEMINI_2_5_PRO_TOOLS_WEB_SEARCH=true

# Cost-effective model for file processing
DEFAULT_FILEUPLOAD_MODEL=meta-llama-3.1-8b-instruct
MODELS_GWDG_META_LLAMA_3_1_8B_INSTRUCT_TOOLS_FILE_UPLOAD=true

# High-quality vision model
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct
MODELS_GWDG_QWEN2_5_VL_72B_INSTRUCT_TOOLS_VISION=true

# Disable redundant models
MODELS_OPENAI_O4_MINI_ACTIVE=false
MODELS_GOOGLE_GEMINI_2_0_FLASH_LITE_ACTIVE=false

Related Configuration

These model configuration variables work in conjunction with other HAWKI settings:

Default Model Selection

Set default models in .env:

DEFAULT_MODEL=gpt-4.1-nano
DEFAULT_WEBSEARCH_MODEL=gemini-2.0-flash
DEFAULT_FILEUPLOAD_MODEL=meta-llama-3.1-8b-instruct
DEFAULT_VISION_MODEL=qwen2.5-vl-72b-instruct

See config/model_providers.php lines 13-18 for default model configuration.

System Models

Configure models for automated tasks:

TITLE_GENERATOR_MODEL=gpt-4.1-nano
PROMPT_IMPROVEMENT_MODEL=gpt-4.1-nano
SUMMARIZER_MODEL=gpt-4.1-nano

See config/model_providers.php lines 42-46 for system model configuration.

Provider Settings

Configure provider-level settings:

# Enable/disable entire providers
OPENAI_ACTIVE=true
GWDG_ACTIVE=true
GOOGLE_ACTIVE=true
OLLAMA_ACTIVE=false
OPEN_WEB_UI_ACTIVE=false

# Provider API configuration
OPENAI_API_KEY=your-key
GWDG_API_KEY=your-key
GOOGLE_API_KEY=your-key

File Converter Configuration

File upload tools require a working file converter:

FILE_CONVERTER=hawki_converter
HAWKI_FILE_CONVERTER_API_URL=127.0.0.1:8001/extract
HAWKI_FILE_CONVERTER_API_KEY=123456

# Or use GWDG Docling
# FILE_CONVERTER=gwdg_docling
# GWDG_API_KEY=your-key

See the .env documentation for complete file converter configuration.

---

For more information about HAWKI's model configuration system, see:

• Model Connection Architecture - Technical details of the model system
• dot Env Configuration - Complete environment variable reference
• Model provider documentation for API keys and endpoints